Network Supervisor's Toolkit

home *** CD-ROM | disk | FTP | other *** search

/ Network Supervisor's Toolkit / Network Supervisor's Toolkit.iso / btrieve / btfiler / btfiler.doc < prev next >

Wrap

Text File | 1996-07-10 | 74.1 KB | 1,909 lines

BTFILER A Btrieve file recovery, viewing and editing utility Version 1.42 By Access Microsystems Inc. 404 Midstreams Road Brick, NJ 08724-3838 (908) 892-2683 CIS: 74040,607 TABLE OF CONTENTS 1. Who made BTFILER? Why? 2. What does BTFILER require? 3. What does BTFILER do? A. Intended actions B. Unintended actions (dare we say BUGS?) 4. Details... A. Starting BTFILER B. The Main Menu C. The File Sub-menu 1. Browsing/Editing a BTRIEVE file a. Moving around b. Editing a record c. Deleting a record d. Adding a record e. The File sub-menu in the Browse/Edit main menu f. The View sub-menu in the Browse/Edit main menu g. Special problems re: variable length records 2. Cloning a Btrieve file 3. Packing a Btrieve file 4. Copying a Btrieve file 5. Test/Rebuild a Btrieve file a. DOS Read test b. Index test c. Rebuild d. Advanced File Recovery 1. Recover EVERY POSSIBLE Record 2. Rebuild Header 6. Import/Export a. Import 1. Unformatted ASCII 2. Comma-Delimited ASCII b. Export 1. Unformatted ASCII 2. Comma-Delimited ASCII 7. Misc. Btrieve Functions a. Set Owner b. Clear Owner c. Statistics d. Btrieve Version e. Create file from BTB file f. Supplemental Index g. Transactions 8. Exiting BTFILER D. The Options Sub-menu 1. Set Colors 2. Set Misc. Parameters 3. Reset Btrieve 4. REGISTER BTFILER E. The Help Sub-menu 1. List Error Codes 2. List Operation Codes 3. Btrieve Page Size Calculator 4. About BTFILER 5. Getting help/making suggestions/future directions 1. Who made BTFILER? Why? BTFILER is a product of Access Microsystems Inc. We do programming in C and C++ under DOS and UNIX, often using Btrieve as a file manager. (If you have a project we might be able to help with, contact us at the phone or Compuserve number on the first page of the documentation or throughout the software.) We have used several programs for looking at, recovering data from, and editing Btrieve files. We have been disappointed by the results. Some crashed, others worked but punished us in the process. We thought that there must be a better way, and set out to design such a product. BTFILER is not quite that product, but what we hope will be the first step in the creation of a line of software for Btrieve users. We have ideas about automating the Btrieve file creation process, allowing the import and export of comma delimited files, as well as allowing editing in a user friendly way (for instance, dates in mm/dd/yy format, binary and packed information in ASCII form, etc.) We can't do all that just now, and so we made what we consider a good first step. If you become a registered user, you can help us mold future products and future updates to BTFILER. Shareware works as a way to ensure that you can try software before you buy only if you support shareware authors. If BTFILER meets a need, please register! Also, think about the possibility of getting a distribution license and making BTFILER part of your Btrieve application. DISCLAIMER - AGREEMENT Users of BTFILER must accept this disclaimer of warranty: "BTFILER is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of BTFILER." For Non-Registered Users: BTFILER is a "shareware program" and is provided at no charge to the user for evaluation. Feel free to share it with your friends, but please do not give it away altered or as part of another system. The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. If you find this program useful and find that you are using BTFILER and continue to use BTFILER after a reasonable trial period, you must make a registration payment of $29.00 (+4.00 S&H) to Access Microsystems Inc. The $29.00 registration fee will license one copy for use on any one computer at any one time. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just as a book cannot be read by two different persons at the same time, a single copy of BTFILER cannot be used in two places at once, unless the license is being violated. Commercial users of BTFILER must register and pay for their copies of BTFILER within 30 days of first use or their license is withdrawn. Site-License arrangements may be made by contacting Access Microsystems Inc. or by filling out the registration form found in REGISTER.DOC or produced by BTFILER. See the Options/Register BTFILER menu option. You are encouraged to pass a copy of BTFILER along to your friends for evaluation. Please encourage them to register their copy if they find that they can use it. All registered users will receive: A copy of the latest version of the BTFILER system. A printed manual. Notice of future upgrades. Information on future products. Support for a MINIMUM of 90 days. A copy of our BU partial BUTIL replacement program. This program STOPs, RESETs Btrieve, shows BTRIEVE version and CLONEs Btrieve files. You may distribute this freely. 2. What does BTFILER require? BTFILER requires: An IBM PC or compatible with 512 K (640K recommended for large variable length records). MS/PC DOS version 2.0 or better. Version 4.00 is a known problem, so if you have a problem and you have version 4.00 of MS/PC DOS, UPGRADE DOS FIRST! Btrieve version 4.0 or better. Make sure to tailor your Btrieve start-up parameters (See "Set Misc. Parameters" in the File Sub-menu). BTFILER also requires and is shipped with the following files: BTFILER.DOC This file BTFILER.BER A file with Btrieve Error codes listed BTFILER.BOP A file with Btrieve Operation codes BTFILER.MNU A Menu Control File BTFILER.HLP A Help file. BTFILER.MSK Formatting information - PROPRIETARY FORMAT! BTFILER.CF1 A configuration file BTFILER.EXE The executable file. Run this to use BTFILER. REGISTER.DOC A file with a BTFILER registration form. (Registration can be printed by the program itself as well.) SAMPLE.BTB A sample BTrieve Build file. An ASCII file used to describe a Btrieve file to be created. AMIMAP.EXE A BONUS utility program that lists the amount of memory taken up by resident programs like Btrieve SAMPLE.BTB A sample BTrieve Build ASCII file, used to create Btrieve Files (File/Misc. Btrieve Functions/Create file from BTB). SAMPLE.BTS A sample BTrieve Supplemental index ASCII file, used to create a Supplemental Index. POL.DAT A sample data file with string, and decimal fields to test comma-delimited import and export. POL.INX A sample .INX file for Comma-delimited import and export. Also presented in Appendix C POL.ASC An example of the output created by using POL.INX to export data from POL.DAT POL.DOC A file layout for POL.DAT BTCLONE.BAT An example of a batch file that takes parameters and builds a keystroke file that is used to automate a BTFILER operation, in this case, CLONE. BTRESET.BAT An example of a batch file that creates a keystroke file to automate a simple BTFILER operation, in this case, reset. For further details on both batch files, see Appendix B. REGISTER.DOC A file containing a registration form. CINSTALL.DAT A Color configuration file. This file contains a single line of text. The line has 7 sets of 3 digit numbers, each 3 digit number representing one of the types of colors used by BTFILER. THIS FILE SHOULD BE PLACED IN A DIRECTORY THAT IS ON YOUR DOS PATH SO THAT YOU WILL ALWAYS READ THE SAME COLOR FILE! The file should look like this: rrrmmmooodddsssbbbnnn Where: rrr=decimal "regular" color. mmm=decimal "menu" color. ooo=decimal "selected menu option" color. ddd=decimal "active data entry field" color. aaa=decimal "status line" color. bbb=decimal "box" color. nnn="Hot" letter in menu option BTFILER may, from time to time, create the following files: BTFILER.CF2 A second configuration file. TMP?????.$$$ Temporary files created to save the state of the screen, etc. These may be deleted if you are SURE that no copy of BTFILER is running on the system or on a network the system is connected to. 3. What does BTFILER do? A. Intended actions BTFILER allows you to TEST and RECOVER data from Btrieve files. In addition to standard sorts of Btrieve testing (Test for consistent prev/next links, etc.) BTFILER also has a DOS File test which reads the entire file and reports if a DOS Critical error (ABORT, RETRY or FAIL) error occurs. You may also rebuild a damaged Btrieve file header, and if really desperate, use our Recover EVERY POSSIBLE Record recovery method, which painfully tries to get every possible record in the file by guessing where the data might be. BTFILER allows you to view, edit, search and delete records in a Btrieve file. BTFILER allows you to Clone a Btrieve file (That is, create an empty Btrieve file with the same key structure and record size as the original). BTFILER allows you to Pack a Btrieve file (That is, create a copy of a Btrieve file less the space left by deleted records) as well as Copy a file (That is, copy records from one Btrieve fiole to another, with the destination file possibly having a different record length and key structure). BTFILER allows you to Import and Export records in an Unformatted ASCII format, a format like BUTIL, Novell's Btrieve Developer's Utility, or NEW with version 1.40, comma-delimited ASCII! BTFILER allows you to create a Btrieve file with a BTrieve Build file (.BTB) file and create a supplemental index using a BTrieve Supplemental (.BTS) file. You may also DROP a supplemental index. BTFILER allows you to begin and end transactions within a single session, and will prompt you to end the transaction if you try to do something that can't be done in a transaction. BTFILER allows you to repeat repetitive tasks by creating keystroke files that get passed back to the keyboard buffer as the program is run. This also allows more technical users to provide easy to use batch files for those less comfortable operating BTFILER directly. (See Appendix B). BTFILER allows you to Set and Clear owners of Btrieve files, displays Btrieve version information, and shows file statistics and key structure. BTFILER lists Btrieve Error codes (arranged numerically) and Operation codes (arranged alphabetically). You may also get details on Btrieve error codes. BTFILER lets you choose from 4 different color sets, or customize colors. B. Unintended actions (dare we say BUGS?) As of this writing date, there are no known bugs. (Kind of reminds us of the compiler that reports, after a successful compile, "None of the errors were found"). It is likely that VERY large variable length records will cause problems with memory (but we have not tested it with very large (>25K) variable length records). Please let us know if you run across any problems. See section 5, Getting help/making suggestions. 4. Details... In the following sections, we detail actions required to make BTFILER do work for you. This assumes you have placed the files mentioned above (What does BTFILER require?) in your "PATH". For instance, if you type in PATH<Press ENTER> from the DOS prompt (commonly "C:\>>") and you see the following: PATH=C:\;C:\DOS;C:\UTIL you should place the BTFILER file in the C:\, C:\DOS or the C:\UTIL directory. You must also have Btrieve loaded, or if so configured, Btrieve or Brequest must be available on the PATH. A. Starting BTFILER At any DOS prompt (or from the directory that BTFILER files reside in, if not on your PATH) type: BTFILER<Press ENTER> If you wish to browse or edit a particular Btrieve file, you may enter that on the command line as well. For example: BTFILER filename.ext<Press ENTER> BTFILER will then take a few seconds to load. Depending upon the settings on the "Set Misc. Parameters" screen (under the "Options" menu) BTFILER may also load Btrieve or Brequest. If you get a message indicating that BTFILER is unable to load Btrieve, load Btrieve from the command line and then go to the "Set Misc. Parameters" screen and ensure that the default Btrieve start up parameters are set correctly. Three other command line parameters are possible. /k:keyfile, where keyfile is the name of a file with keystrokes for BTFILER to use on start-up. See Appendix B for details on creation of a keystroke file. /c:myfile.cf2 where myfile.cf2 is a version of the BTFILER.CF2 configuration file created under Options/Set Misc. Parameters. If you need to, you can create 2 or more configuration files, and with the /c command line parameter, indicate which should be loaded. An additional parameter /L tells BTFILER to create a log file of test/recovery activity called BTFILER.LOG. You may also specify a filename and extension for the logfile by passing a parameter /L:filename.ext. All messages indicating no problem contain the letters OK, all messages indicating some failure contain the letters FAIL. As BTFILER is loaded a screen will appear briefly to list the registered owner of this copy of BTFILER (Thank You!) or to remind you that you are currently using an unregistered copy. This screen will remain on the screen for a few seconds, and then you may press any key to continue. Note that the status line (the bottom line on the screen) will almost always tell you what BTFILER is doing or what you should do next. B. The Main Menu The Main Menu is a menu bar running across the top of the screen. This menu has three options: File, Options, and Help. You can maneuver around the menu by using arrow keys and the ENTER key, as well as ALT-Letter combinations. (For instance, if no sub-menu is "dropped," you may press the ALT and the H key to get to the Help sub-menu. To exit BTFILER, you can press ESC (or press ESC twice if a sub-menu is "dropped") and you will return to DOS. You may also exit by pressing ENTER while the Exit option of the File sub-menu is highlighted. C. The File Sub-menu The File sub-menu includes four options: Browse/Edit Btrieve File, Clone Btrieve File, Pack Btrieve File,and Exit. 1. Browsing/Editing a BTRIEVE file When ENTER is pressed (or ALT-B is pressed) in the File sub-menu, you will be prompted to enter a file name. The default is "*.DAT" If you supplied a file name on the command line when starting BTFILER, or if you have already browsed/edited a Btrieve file, that will be the default. If you press ENTER with a filename containing '?' or '*' (an "ambiguous" file name) BTFILER will present you with a menu of files like the file name entered. If the menu is presented, use the arrow keys to get to the correct file and press ENTER. You may also press ESC and re- enter the file name. If you press ESC while entering the file name, you will return to the menu. Once the Btrieve file selected is opened and some of the records are loaded, you will be presented with a screen with three parts: The Browse/Edit Main Menu bar The Scale The Data area. The Browse/Edit Main Menu bar works very much like the main menu described earlier. One difference is that the menu here is not the focus of activity. When you start browsing/editing a file, no options on the Browse/Edit Main Menu are highlighted. The focus is on the data below. To get to the Browse/Edit Main Menu, simply press ALT and F (to get to the File sub-menu) or ALT and V (to get to the View sub-menu). The Scale lets you know what offset within the record you are looking at. The right and left arrows will move you 10 positions to the left or right. The Data area of the screen is a straight listing of the data in the records in the file. Note that there may be some strange characters on the screen. This is perfectly normal if the Btrieve file contains binary or packed data. a. Moving around Use the arrow keys and the Page-up and Page-down keys to move around. When you enter the screen, the top line will be highlighted. Use the down arrow to highlight another record, and use the left and right arrows to view the rest of a record that is larger than 80 characters. b. Editing a record To edit a Btrieve record, use the arrow keys to highlight the record you wish to edit and press ENTER. You will be presented with a menu asking if you want to Edit this record, Delete this record, Add a record like this one, or Continue Browsing. With Edit this record highlighted, press ENTER. You will be presented with a window on the screen that will allow you to edit, 256 characters at a time, the record that was selected. By default you will be doing a HEX edit. To switch back and forth between HEX and ASCII editing, press the TAB key. Use the cursor movement keys to move around the data. To exit the editing screen, press ESC. If you make changes, a Yes or No box will appear reminding you that the data was changed, and asking if you wish to save changes. Press 'Y' to save changes, or 'N' to abandon. It is possible to make changes that Btrieve won't allow (creating a duplicate record in a key that does not allow duplicates or trying to modify a non-modifiable key) and if you do that you will get an error message. c. Deleting a record To delete a Btrieve record, use the arrow keys to highlight the record you wish to delete and press ENTER. You will be presented with a menu asking if you want to Edit this record, Delete this record, Add a record like this one or Continue Browsing. With Delete this record highlighted, press ENTER. You will be asked if you are sure you want to delete the record. Press 'Y' to delete it, or 'N' to not delete the record d. Adding a record like the current record To add a Btrieve like the record you are currently editing (using an existing record as a model ), use the arrow keys to highlight the record most like the one you wish to add and press ENTER. You will be presented with a menu asking if you want to Edit this record, Delete this record, Add a record like this record, or Continue Browsing. With Add a record like this record highlighted, press ENTER. You will be presented with a screen very much like the editing screen. Make whatever changes you wish. When you are done, press ESC. You then will be asked if you wish to save the changes. Press 'Y' to save the new record, or 'N' to abandon the changes. It is possible to try to add a new record that Btrieve won't allow (creating a duplicate record in a key that does not allow duplicates) and if you do that you will get an error message. e. The File sub-menu in the Browse/Edit main menu This menu allows you to select a new file or exit to the Main Menu. To get to the Files sub-menu in the Browse/Edit main menu while browsing data, press the ALT and F keys. f. The View sub-menu in the Browse/Edit main menu To get to the View sub-menu in the Browse/Edit main menu while browsing data,press the ALT and V keys. The View sub-menu in the Browse/Edit main menu has four options: Key Only, Set Key Number, Begin View With, and Search. Key Only allows you to switch from viewing the entire record to a key only browse. To use the check-box, press the space bar and a check mark will appear and disappear. If the check mark appears when ENTER is pressed, only the key will be displayed. Set Key Number allows you to set the order you wish to view the data. The field where you enter the key number will default to the current key number. Begin View With allows you to jump to a particular key value in the file. Search allows you to search out a record in the file looking for a particular string of text. The search can be global or starting from the top line on the screen, and it can be case sensitive or insensitive to the case of the characters entered (upper an lowercase treated the same). If the string is found, the first record with the string will be displayed with the matching text flashing. g. Special problems with Variable length records. Variable length records present a special problem when building a generic Btrieve file viewer. The only limit to the size of a Btrieve variable length record is 64K. Most Variable length records are MUCH shorter. If you work with variable length records, please make sure you set your "Largest variable record" under "Set Misc. Parameters" under "Options" on the Main Menu to a value bigger than any record you might expect to read in If you edit a variable length record, it will be written back at the same length. 2. Cloning a Btrieve file With this option, you can make an empty copy of an existing Btrieve file. You must enter the name of the Btrieve file as well as the name of the "clone" file to be created. 3. Packing a Btrieve file Like most DOS files, Btrieve files get bigger as records are added, but do not shrink as records are deleted. This can be especially noticeable if you have a transaction file that grows and grows until some month or year end procedure, and then is purged. The space where the deleted records were is still in the file. This space will eventually be used again, but what if you can't wait? That is where Packing comes in. Simply supply the name of the file to be packed, and BTFILER will rewrite it without the space where the deleted records were. The original file is saved with an extension of .BAK. Please ensure that the packed file is good and then you may delete the .BAK. 4. Copying a Btrieve file This operation allows you to copy data from one btrieve file to another, possibly with different key structure and record length. 5. Test/Rebuild a Btrieve file This menu allows you to test a Btrieve file to ensure that DOS can read the entire file without a DOS Critical error (Abort, Retry, Fail...), tests that all indices (keys) of a Btrieve file are correctly linked, and allows you to rebuild a damaged file. The explanations for these options follows. a. DOS Read Test This option allows you to test a file to ensure that DOS can read through the entire file. The file in question need not even be a Btrieve file. b. Index Testing This option tests a Btrieve file to ensure that the links in the file (in both directions for each key) are correct. A record could be written to disk in such a way that it points to itself, or to some other record that is not the correct record. This test will look for such problems. c. Rebuild If you don't normally read documentation, PLEASE READ THIS! This is a "last resort" procedure that should be used only if no recent backup exists. While there is little chance of damage occurring to your Btrieve file since the original is opened in read-only mode, and the original is saved as a .BAK file, backups are the best bet! There is no guarantee that this procedure will get all records, although it is likely that almost all records will be recovered. This procedure uses physical positioning (not logical positioning, going through the file via a key) to read from the first physical record to the last. If an error occurs while proceeding from beginning to end, the program tries to step directly to the last record, and tries to read from end to beginning. If there is only one record that has a problem, all but that one record should be recovered. d. Advanced File Recovery 1. FULL Rebuild If you don't normally read documentation, PLEASE READ THIS! This is a "REALLY last resort" procedure that should be used only if no recent backup exists. While there is little chance of damage occurring to your Btrieve file since the original is opened in read-only mode, and the original is saved as a .BAK file, backups are the best bet! There is no guarantee that this procedure will get all records, although it is likely that almost all records will be recovered. In addition, this procedure may recover EXTRA records, probably index information that is mis-read as data. NOTE: This procedure will not work on files with data compression, nor will it work on key only files! If you are not using Btrieve/Brequest version 5.1x, this may or may not work. ALWAYS keep a backup of the damaged file to try something else if this fails. This procedure uses our knowledge of Btrieve files to try to find records at EVERY POSSIBLE record location in the file, and then goes a step further: If a status other than Status 43 (invalid positioning information) it will attempt to read the portion of the file where we think there might be a record via standard DOS calls. Not for the squeemish, and you will have to look through the file to find any records that are not real data. Try after all else fails. What have you got to lose? If this doesn't find your data, they aren't there! e. Header Rebuild This operation should ALWAYS be tried only on a copy of the damaged file, so that you may still try ther recovery options if this operation fails. You MUST have another file that is identical in key structure and page size and record length to perform this operation. This operation will copy the header from the undamaged file, modify some values in the file to ensure that the header will reflect the current file length of the damaged file, and then will place you in the file rebuild screen (described above) and attempt to recover all records. 6. Import/Export Select Import/Export from the File menu under the Main Menu and you will be presented with a menu that allows you to import or export records to or from a Btrieve file. Upon selecting Import or Export. you will be presented with a menu that allows you to import or export Unformatted ASCII (BUTIL format or flat unformatted ASCII). You will then be presented with a screen that allows you to specify the Source and Destination file. In the case of Comma-delimited ASCII, you will also have to specify a description file in a format like POL.INX, included on disk as well as in Appendix C of this manual. If you choose Unformatted ASCII, you will also be allowed to choose between a BUTIL style ASCII file or a flat ASCII file, without the length specifier required by BUTIL. If you choose to NOT use the BUTIL format, the file in question should be a fixed length record with NO binary data. The length of the record for ASCII files not in the BUTIL style is the number of bytes until the ASCII CR/LF characters are found. In a binary file, it is possible that these characters might naturally occur, causing BTFILER to think that the record ends in the middle of a field of binary data. This is clearly not a good thing. The format of the BUTIL style ASCII file is as follows: 29,this is a 29 character record<CR/LF> That is, each record should contain the decimal length followed by a comma, followed by the record, padded with spaces if needed to make it the length specified, followed by CR/LF (hex 0D0A). If you are not using the export file to communicate directly with another Btrieve utility that understands BUTIL or flat unformatted ASCII, you are almost always better off exporting data in the comma-delimited ASCII format. If you have .DDF files (files created by applications like Xtrieve by Novell) please contact us for information on our latest addition, BTVIEWER. BTVIEWER allows for import and export of views created by using .DDF files, as well as the intellegent query of the database, with display and editing done on a field level that allows, for instance, dates to be edited in the form of 'mm/dd/yyyy' and decimal or binary values to be edited as numeric ASCII values (i.e. '123.45') 7. Misc. Btrieve Functions a. Set Owner Btrieve allows users to set "owners" for files. By setting an "owner," a Btrieve user can choose to allow no access to the file without the owner name or allow read-only access, and the user can choose whether the file will be encrypted or not. It is important to remember that if you set an owner for a Btrieve file, any program that is to access it (including BTFILER) must know that user name, and the user must remember the user name if s/he wishes to Clear the owner (see below). When the File/Misc. Btrieve Functions/Set Owner menu option is selected, BTFILER displays a box with three fields. In the first field, enter the name of the file for which an owner name is to be set. In the second field, enter the string that will become the new "owner." In the third field you will be presented with a menu that will allow you to choose whether or not to allow read-only access without the owner name, and whether or not the Btrieve file should be encrypted. Highlight the appropriate option and press ENTER. If you have selected an option that calls for encryption, some time may be required. Please be patient. b. Clear owner When the File/Misc. Btrieve Functions/Clear Owner menu option is selected, BTFILER displays a box with two fields. In the first field, enter the name of the file for which an owner name is to be cleared. In the second field, enter the current "owner." If you have selected a Btrieve file that had an owner name set with encryption, some time may be required. Please be patient. c. Statistics When the File/Misc. Btrieve Functions/Statistics menu option is selected, BTFILER prompts for a file name to be entered. If the file name entered exists and is a valid Btrieve file, BTFILER will display information about the file, including the number of records and number of keys, the record length, the file length, and some information on the actual space used, on average, for each record in the file and the % utilization. Information on the keys will appear in a box on the lower portion of the screen. If more keys than will fit on one screen are present, use the arrow or page down keys to see the rest of the key information. d. Btrieve Version When the File/Misc. Btrieve Functions/Btrieve Version menu option is selected, BTFILER displays a small box that gives Btrieve version information, for instance "Btrieve Version 5.10 for Networks." Press any key to continue. e. Create file from BTB file Select this option to create a new Btrieve file. You will need to supply the name of a BTrieve Build file (BTB) and a name for the new file. This option is similar to BUTIL's -CREATE option, but with much better error handling. Please see the sample BTB file called SAMPLE.BTB provided with BTFILER system and listed in Appendix A. f. Supplemental Index Selecting this menu option will give you another menu, where you may create or drop a supplemental index. You must have a .BTS file (see SAMPLE.BTS for a sample of the format). Enter the .BTS file name in the first field, and the name of the Btrieve file to add the supplemental index to in the next. If you choose to drop a supplemental index, you will be asked to supply the Btrieve file name and the index number to drop. Use File/Misc. Btrieve Functions/Statistics to determine the key number to drop. g. Transactions You may begin a transaction, or if one is already in progress, end a transaction using this menu option. When ending a transaction, you may choose to simply end the transaction (changes saved) or you may abandon the transaction (changes lost). 8. Exiting BTFILER Choose this option to exit BTFILER and return to DOS. You may also exit by pressing ESC (or by pressing ESC twice if you are in the File, Options, or Help sub-menu). D. The Options Sub-menu 1. Set Colors Choose from the four color sets mentioned. 2. Set Misc. Parameters Choose this option and you will be presented with a screen that looks like this: Set BTFILER Misc. Options [_] Load Btrieve? [_] Load Brequest? Browse/Edit Open Mode: ___________ Btrieve load options: ________________________ Brequest load options: ________________________ Memory to save for Btrieve: ______ Owner name for Btrieve: ____________________ Largest variable record: _____ Print report to (LPT1, etc): ________________________ Default File Name Mask: _____________________________ (i.e. "*.DAT") The first two questions ask if you would like to load Btrieve and/or Brequest. It might be better (from a memory control standpoint) to have Btrieve loaded BEFORE you run BTFILER, but it is often convenient to allow BTFILER to load it for you. The next question allows you to determine the open mode when files are browsed or edited (using the File/Browse-Edit Btrieve File menu option). If you wish to ensure that the file is not changed, set Read-Only. If working on a network, and you wish to have exclusive access to a file, set Exclusive. To verify data as it is written (normally not needed and not very effective in any case) set Verify. If you are working on a file where you are starting fresh and have nothing to lose, you may want to set Accelerated. Note that Accelerated has no effect on speed of reading the file, and will leave your file damaged if it is not closed properly. This option is included for completeness, not because we recommend this option. All options are presented to you on a menu. The next two questions allow you to specify Btrieve and/or Brequest start-up (load) options. Please see your Btrieve or Brequest manual for specifics. Also, note that it is possible to give invalid load options to Btrieve that will prevent Btrieve from being loaded. In that case, load Btrieve BEFORE you enter BTFILER and then correct the Btrieve load options. The amount of memory to save for Btrieve is dependent upon the version of Btrieve you are using, the load options you specify, and the availability of extended (or is that expanded...) memory. Run Btrieve with the load parameters you expect to use and then run AMIMAP.EXE (a utility that reports on the space taken up by resident programs) and note how much space is taken up by Btrieve. Add several thousand bytes to this for good luck, and this will reserve enough memory for Btrieve. 130000 is a safe number to use if this is too much for you to figure out. Owner name is the owner name to use when opening up Btrieve files that require an owner name. If you don't know what this means, you probably don't need to fill this in. Largest variable record is important if you are going to read variable length record Btrieve files. If you have too small a number here, you might get an error 22 (buffer too short). If you have too large a number here, you may have memory problems. Print report to specifies where reports (currently only the registration form and printing this documentation) should print. This should almost always be LPT1 or PRN. Try those if in doubt. The default file mask allows you to set the default file mask without having to enter it on the command line each time. The default is "*.DAT", but for many "*.BTR" is more convenient. 3. Reset Btrieve Issues a RESET command to Btreive. 4. REGISTER BTFILER If you like what you see, and would like to make sure that shareware programs like BTFILER are produced, you must register and pay for the use of the program. The $29.00 requested (for a single copy) is a steal, and to further entice you, we even made up this neat utility to print out the registration form for you. Simply fill in the requested information and the form will be printed. Fill in the number of single user or site licenses, the size disks you wish to receive,and mail it to the address on the form. You can always just jot down your name and address and mail that in with a notation that you are registering for BTFILER, but what the heck, that's what computers are for! If you need to use a credit card, you may register on-line on CompuServe. Type GO SE at any prompt and you will go to Software Excitement's connect-charge free section. Choose menu option 7 (*** Register Shareware Software ***), then option 2 (Order by Product Title). BTFILER will be listed on the first page or two. Enter the number to the left of BTFILER and supply the requested information. Credit card orders may also be placed by phone at (1-800-444-5457). If you have any questions ordering, please contact us at the phone number or CIS ID listed throughout the documentation and the program. If you register, you will get: A copy of the latest version of the BTFILER system. A printed manual. Notice of future upgrades. Information on future products. Support for a MINIMUM of 90 days. A copy of our BU partial BUTIL replacement program. This program STOPs, RESETs Btrieve, shows BTRIEVE version and CLONEs Btrieve files. You may distribute this freely. E. The Help Sub-menu These options are self explanatory (and non- threatening if you just try them out). 1. List Error Codes 2. List Operation Codes 3. Page Size Calculator - For the designer of Btrieve file databases, allows for the creation of files with the minimum amout of space wasted. 3. About BTFILER 5. Getting help/making suggestions/future directions If you are a registered user, or if you are having a problem getting started, PLEASE contact us at: Access Microsystems Inc. 404 Midstreams Road Brick, NJ 08724-3838 (908) 892-2683 CIS: 74040,607 We generally work 9 to 5, Monday through Friday. We may not always be here when you call, but we will try to return calls if you leave a SPECIFIC message. We monitor Compuserve (CIS) messages daily for support purposes, but understand that not everyone is ready for E-Mail. We seek your advice on future directions for this and other products. We expect (if the interest in BTFILER warrants) a follow-on product that will add some more advanced editing, as well as more powerful utilities for doing things like importing and exporting data and creating files. We would love your advice. APPENDIX A - Listing of SAMPLE.BTB The following is a listing of SAMPLE.BTB, An ASCII file that describes a BTRIEVE file to be built with BTFILER's File/Misc. Btrieve Functions/Create File from BTB file menu option. Please modify this file to create the type of file YOU need. Keep the BTB file you create on line to rebuild the file you create as needed. # # This line (and all lines beginning with '#') are COMMENTS. # # This is a sample BTrieve Build (BTB) file. It allows for the # creation of Btrieve files in BTFILER. It does the same thing # as the BUTIL -CREATE function, but with one significant # difference: Error diagnostics are clearer. This removes (I # think) the most significant problem with the BUTIL -CREATE # process. Someday an interactive create utility will be part # of BTFILER, but until then, this will have to do... # # Case is not important, and some fields are optional (as # noted in comments). # # These are the fields possible listed in order of appearance # in the file level settings section: # # RECORD LEN=n # PAGE SIZE=n, multiple of 512 # VARIABLE=<YES or NO> # BLANK TRUNCATION=<YES or NO> OPTIONAL! # DATA COMPRESSION=<YES or NO> # FREE SPACE THRESHOLD=<10, 20 or 30> # ALTERNATE FILE=<filename> OPTIONAL if no alternate key # INCLUDE DATA=<YES or NO> OPTIONAL! # NUMBER OF KEYS=n # # # These are file level settings, with more details... # RECORD LEN=131 # # In the Help menu, see "Calculate Page Size" to find optimal size. # PAGE SIZE=1536 VARIABLE=NO # # BLANK TRUNCATION is only meaningful with variable length # records, so this BLANK TRUNCATION= line is optional. # BLANK TRUNCATION=NO DATA COMPRESSION=NO # # FREE SPACE THRESHOLD=n, where 'n' is 10, 20 or 30 ONLY! # FREE SPACE THRESHOLD=20 # # ALTERNATE FILE=fname, where fname is the name of a file like # UPPER.ALT. This line is optional IF no ALTERNATE=YES # key segments exist. # ALTERNATE FILE=UPPER.ALT # # INCLUDE DATA=<Y or N> is used to determine if the file is key only # Data only, or key and data. INCLUDE DATA= line is OPTIONAL! # # For KEY ONLY: INCLUDE DATA=NO # NUMBER OF KEYS=1 # and key length is == to record length. # # For DATA ONLY: INCLUDE DATA=YES # NUMBER OF KEYS=0 # INCLUDE DATA=Yes # # NUMBER OF KEYS= is used as a cross check of the segments # passed below. In case of a conflict, the option is given # to accept the key count reflected in the segments, or # abandoning creation of the file. # NUMBER OF KEYS=2 # # END OF FILE LEVEL SETTINGS! # # This marks the beginning of key segment level information. # If I were you, and I were creating BTB files, I would # place a large comment band between each key segment # to remind myself what I think I am doing. Just a # thought... # # The lines for each key segment are in the following order: # # START=n, where 'n' is the starting position of the key # LEN=n, where 'n' is the length of the key # MODIFIABLE=s, where 's' is Y or N (or YES or NO or Yes or...) # Allows Modifications to be made to the key? # DUPLICATES=s, ditto above...Allows Duplicate keys? # ALTERNATE=s, where 's' is as above. Alternate Collating Sequence? # DESCENDING=s, like above. Sorts Hi to Lo? # TYPE=t, where 't' is EXACTLY one (case difference OK) of the following: # # "String", # "Integer", # "Float", # "Date", # "Time", # "Decimal", # "Money", # "Logical", # "Numeric", # "Bfloat", # "Lstring", # "Zstring", # "Unsigned Binary", # "Autoincrement", # # NULL=n, where 'n' is the decimal NULL value (commonly 0 or 32) OR # NULL=N/A to explicitly state no NULL value. # NULL= is OPTIONAL. # SEGMENT=s, where 's' is Y or N (or Yes or N0...). The number of # segments with a SEGMENT=No value should be the same # as the number of keys you declare. # # # Key 0/Segment 1 # START=1 LEN=11 MODIFIABLE=n DUPLICATES=n ALTERNATE=n DESCENDING=n TYPE=STRING NULL=N/A SEGMENT=NO # # key 1/segment 1 # START=12 LEN=30 MODIFIABLE=y DUPLICATES=y ALTERNATE=y DESCENDING=n TYPE=STRING NULL=N/A SEGMENT=YES # # key 1/segment 2 # START=1 LEN=11 MODIFIABLE=y DUPLICATES=y ALTERNATE=y DESCENDING=n TYPE=STRING NULL=N/A SEGMENT=NO # # That's all, folks! # Appendix A - Listing of SAMPLE.BTB and SAMPLE.BTS Use the following file (supplied on disk as well) that allows you to create a Btrieve file by describing it in an ASCII file. Modify it for your needs and run the File/Misc. Btrieve Functions/Create file using BTB file menu option. When asked, supply the name of the BTB file you have modified for your use, or use the SAMPLE.BTB file to see how the system works. # # This line (and all lines beginning with '#') are COMMENTS. # # This is a sample BTrieve Build (BTB) file. It allows for the # creation of Btrieve files in BTFILER. It does the same thing # as the BUTIL -CREATE function, but with one significant # difference: Error diagnostics are clearer. This removes (I # think) the most significant problem with the BUTIL - CREATE # process. Someday an interactive create utility will be part # of BTFILER, but until then, this will have to do... # # Case is not important, and some fields are optional (as # noted in comments). # # These are the fields possible listed in order of appearance # in the file level settings section: # # RECORD LEN=n # PAGE SIZE=n, multiple of 512 # VARIABLE=<YES or NO> # BLANK TRUNCATION=<YES or NO> OPTIONAL! # DATA COMPRESSION=<YES or NO> # FREE SPACE THRESHOLD=<10, 20 or 30> # ALTERNATE FILE=<filename> OPTIONAL if no alternate key # INCLUDE DATA=<YES or NO> OPTIONAL! # NUMBER OF KEYS=n # # # These are file level settings, with more details... # RECORD LEN=131 # # In the Help menu, see "Calculate Page Size" to find optimal size. # PAGE SIZE=1536 VARIABLE=NO # # BLANK TRUNCATION is only meaningful with variable length # records, so this BLANK TRUNCATION= line is optional. # BLANK TRUNCATION=NO DATA COMPRESSION=NO # # FREE SPACE THRESHOLD=n, where 'n' is 10, 20 or 30 ONLY! # FREE SPACE THRESHOLD=20 # # ALTERNATE FILE=fname, where fname is the name of a file like # UPPER.ALT. This line is optional IF no ALTERNATE=YES # key segments exist. # ALTERNATE FILE=UPPER.ALT # # INCLUDE DATA=<Y or N> is used to determine if the file is key only # Data only, or key and data. INCLUDE DATA= line is OPTIONAL! # # For KEY ONLY: INCLUDE DATA=NO # NUMBER OF KEYS=1 # and key length is == to record length. # # For DATA ONLY: INCLUDE DATA=YES # NUMBER OF KEYS=0 # INCLUDE DATA=Yes # # NUMBER OF KEYS= is used as a cross check of the segments # passed below. In case of a conflict, the option is given # to accept the key count reflected in the segments, or # abandoning creation of the file. # NUMBER OF KEYS=2 # # END OF FILE LEVEL SETTINGS! # # This marks the beginning of key segment level information. # If I were you, and I were creating BTB files, I would # place a large comment band between each key segment # to remind myself what I think I am doing. Just a # thought... # # The lines for each key segment are in the following order: # # START=n, where 'n' is the starting position of the key # LEN=n, where 'n' is the length of the key # MODIFIABLE=s, where 's' is Y or N (or YES or NO or Yes or...) # Allows Modifications to be made to the key? # DUPLICATES=s, ditto above...Allows Duplicate keys? # ALTERNATE=s, where 's' is as above. Alternate Collating Sequence? # DESCENDING=s, like above. Sorts Hi to Lo? # MANUAL=s, like above. Manual key? OPTIONAL! # TYPE=t, where 't' is EXACTLY one (case difference OK) of the # following: # # "String", # "Integer", # "Float", # "Date", # "Time", # "Decimal", # "Money", # "Logical", # "Numeric", # "Bfloat", # "Lstring", # "Zstring", # "Unsigned Binary", # "Autoincrement", # # NULL=n, where 'n' is the decimal NULL value (commonly 0 or 32) OR # NULL=N/A to explicitly state no NULL value. # NULL= is OPTIONAL. # SEGMENT=s, where 's' is Y or N (or Yes or N0...). The number of # segments with a SEGMENT=No value should be the same # as the number of keys you declare. # # # Key 0/Segment 1 # START=1 LEN=11 MODIFIABLE=n DUPLICATES=n ALTERNATE=n DESCENDING=n TYPE=STRING NULL=N/A SEGMENT=NO # # key 1/segment 1 # START=12 LEN=30 MODIFIABLE=y DUPLICATES=y ALTERNATE=y DESCENDING=n TYPE=STRING NULL=N/A SEGMENT=YES # # key 1/segment 2 # START=1 LEN=11 MODIFIABLE=y DUPLICATES=y ALTERNATE=y DESCENDING=n TYPE=STRING NULL=N/A SEGMENT=NO # # That's all, folks! # Use the following file (supplied on disk as well) that allows you to create a Supplemental Index for a Btrieve file by describing it in an ASCII file. Modify it for your needs and run the File/Misc. Btrieve Functions/Supplemental Index/Create menu option. When asked, supply the name of the BTS file you have modified for your use, or use the SAMPLE.BTS file to see how the system works. # # This line (and all lines beginning with '#') are COMMENTS. # # This is a sample BTrieve Supplemental Index (BTS) file. # It allows for the creation of a supplemental index (key) # for Btrieve files in BTFILER. It does the same thing # as the BUTIL -SINDEX function, but with one significant # difference: Error diagnostics are clearer. This removes (I # think) the most significant problem with the BUTIL - SINDEX # process. Someday an interactive utility for this will be part # of BTFILER, but until then, this will have to do... # # Case is not important, and some fields are optional (as # noted in comments). # # This field is the only field possible on the file level section: # # ALTERNATE FILE=<filename> OPTIONAL if no alternate key # # # # ALTERNATE FILE=fname, where fname is the name of a file like # UPPER.ALT. This line is optional IF no ALTERNATE=YES # key segments exist. # ALTERNATE FILE=UPPER.ALT # # END OF FILE LEVEL SETTINGS! # # This marks the beginning of key segment level information. # If I were you, and I were creating BTS files, I would # place a large comment band between each key segment # to remind myself what I think I am doing. Just a # thought... # # The lines for each key segment are in the following order: # # START=n, where 'n' is the starting position of the key # LEN=n, where 'n' is the length of the key # MODIFIABLE=s, where 's' is Y or N (or YES or NO or Yes or...) # Allows Modifications to be made to the key? # DUPLICATES=s, ditto above...Allows Duplicate keys? # ALTERNATE=s, where 's' is as above. Alternate Collating Sequence? # DESCENDING=s, like above. Sorts Hi to Lo? # MANUAL=s, like above, Manual key? OPTIONAL! # TYPE=t, where 't' is EXACTLY one (case difference OK) of the following: # # "String", # "Integer", # "Float", # "Date", # "Time", # "Decimal", # "Money", # "Logical", # "Numeric", # "Bfloat", # "Lstring", # "Zstring", # "Unsigned Binary", # "Autoincrement", # # NULL=n, where 'n' is the decimal NULL value (commonly 0 or 32) OR # NULL=N/A to explicitly state no NULL value. # NULL= is OPTIONAL. # SEGMENT=s, where 's' is Y or N (or Yes or N0...). The number of # segments with a SEGMENT=No value MUST be one in this case # since only a single supplemental index can be declared # at once. # # Segment 1 # START=1 LEN=22 MODIFIABLE=n DUPLICATES=n ALTERNATE=n DESCENDING=n TYPE=STRING NULL=N/A SEGMENT=NO # # That's all, folks! # Appendix B - Using Keystroke files Beginning with Version 1.30, BTFILER allows for use of keystroke files to automate some program functions. What must be in the file is every keystroke that is required to run a particular operation. The only exception is the keystroke required to bypass the registration reminder screen. This screen is passed over if a keystroke file is being played. Most characters are self explanatory, but some special characters may also be entered. '!' is used where an enter key would be played, and '#' substitutes for ESC. Control characters may be entered as the caret key ('^') followed by the actual letter (i.e. 'C'). If the characters '^' 'C' are in a keystroke file, and they are played back while in a data entry field, they will clear the field. It is easiest to use the mnemonic characters (those highlighted on the menus) to select options, and note currently there is a limit of 200 characters that may be played back. Below two batch files are listed that create keystroke files on the fly and then feed them to BTFILER. BTCLONE.BAT echo off if '%1' == '' goto NO_PARMS if '%2' == '' goto NO_PARMS goto OK :NO_PARMS echo USAGE: BTCLONE existing_file new_clone_file goto END :OK rem rem 'C' to choose Clone on opening menu, %1 the Btrieve file, '!' for ENTER, rem %2 the New file, '!' for enter, and '###' for ESC's. rem echo C%1!%2!### >btclone.txt btfiler /k:btclone.txt del btclone.txt :END BTRESET.BAT echo off rem rem '#' (ESC) to go to top menu bar, 'O' for Options, rem 'E' for Reset Btrieve, and rem Lots of "#' (ESC) to get back out. rem echo #OE### >btreset.txt btfiler /k:btreset.txt del btreset.txt :END Appendix C - .INX Description files for Comma-Delimited ASCII Import and Export Beginning with Version 1.40, BTFILER allows for use of .INX files to describe fields to be imported and exported in Comma-delimited files. The example below, for instance, only exports or imports 6 fields, whereas the file might contain many more fields. It is almost certainly more useful to EXPORT a partial file than it would be to IMPORT a partial file. If you have a need for importing and exporting from files for which you already have .DDF files, check for our BTVIEWER program, probably available by July, 1992, with the filename BTVUnn.ZIP, where 'nn' is a version number. If you have need for import and export with .DDF files before that time, drop us a line or call and we will see if you can get an early BETA version. # # This line, and all lines beginning with '#' are comments # # This file will allow you to import and export data from Btrieve # files in a variety of ways. Since you define what fields are in # or should be written to the ASCII comma delimited file, you can # do some pretty neat stuff, like eliminating fields from data # files by exporting only what you really want and importing to a # new file the selected fields. # # The format of the information for each field is as follows: # # FIELD NAME=s # BTRIEVE START=n # BTRIEVE LEN=n # FIELD TYPE=s # ASCII LEN=n # ASCII DECIMALS=n # # 'FIELD NAME' is essentially a comment for now. # # 'BTRIEVE START' is the position within the Btrieve file where # this field is (or in the case of import, where the data should # go). The first position in the file is 1. # # 'BTRIEVE LEN' is the length of the field in the Btrieve fle in # it's native format. Note, for instance, that Btrieve DATE fields # are 4 bytes. # # 'FIELD TYPE' is one of the following: # # "String" # "Integer" # "Float" # "Date" # "Time" # "Decimal" # "Money" # "Logical" # "Numeric" # "Bfloat" # "Lstring" # "Zstring" # "Unsigned Binary" # "Autoincrement" # # NOTE: Only meaningful for IMPORT is a fieldtype of IGNORE. What this # does is ignore the field in the ASCII comma-delimited file. This # allows you to import files that have fields that you do not wish # to import. # # 'ASCII LEN' is the length the field should take in the ASCII # file. # # 'ASCII DECIMALS' is only meaningful for numbers. N/A if it does not apply. # # The ASCII output file will look something like this: # # "Jones ","Bob ","404 Midstreams Road","Brick","NJ",08724 # # In the above case, the first 5 fields might have been STRING fields, # and the last field might have been Numeric, Decimal, or Integer. # # Field 1 # FIELD NAME=POL-PO Num BTRIEVE START=1 BTRIEVE LEN=6 FIELD TYPE=string ASCII LEN=6 ASCII DECIMALS=N/A # # Field 2 # FIELD NAME=POL-Sequence BTRIEVE START=7 BTRIEVE LEN=3 FIELD TYPE=string ASCII LEN=3 ASCII DECIMALS=N/A # # Field 3 # FIELD NAME=POL-SKU BTRIEVE START=10 BTRIEVE LEN=7 FIELD TYPE=string ASCII LEN=7 ASCII DECIMALS=N/A # # Field 4 # FIELD NAME=POL-Unit Retail BTRIEVE START=17 BTRIEVE LEN=5 FIELD TYPE=decimal ASCII LEN=10 ASCII DECIMALS=2 # # Field 5 # FIELD NAME=POL-Cost BTRIEVE START=22 BTRIEVE LEN=5 FIELD TYPE=decimal ASCII LEN=10 ASCII DECIMALS=2 # # Field 6 # FIELD NAME=POL-Ord Qty BTRIEVE START=93 BTRIEVE LEN=4 FIELD TYPE=decimal ASCII LEN=10 ASCII DECIMALS=0 # # This is just a demo. Lots of fields follow, we just # picked these to extract. Note that field 6 is not # adjacent to field 5. The order that the fields are # defined dictates their order in the export file, or # in the case of imports, the fields must be defined in # the order the fields appear in the import file. #